package com.nc.mem.serial.graph.boot;

import java.util.Map;

import com.nc.mem.serial.Serializer;

/**
 * ProvisionService is the public api to other modules hook-up with this module through the
 * ServiceLoader API or other injection mechanisms. <br/>
 * <br/>
 * 
 * @author cmuramoto
 */
public interface ProvisionService {

	/**
	 * Abstractions are API's that provide a common interface presented to the user code and rely on
	 * many implementations in their own code. <br/>
	 * To supply abstractions the following conditions must be met:
	 * <ol>
	 * <li>The serializer presented in the entry must be able to serialize not only the classes
	 * presented in the value, but also the ALL of the children of these classes.</li>
	 * <li>In frozen mode, the parent classes must be presented in
	 * {@link ProvisionService#installableMappings()} if they are abstract or interfaces.</li>
	 * <li>If by any chance the user code presents a concrete reference to the API, there are
	 * chances of class cast exceptions to occur.</li>
	 * </ol>
	 * 
	 * @return
	 */
	Iterable<Map.Entry<Serializer, Iterable<Class<?>>>> installableAbstractions();

	/**
	 * A set of closure-like classes (such as {@link java.util.Comparator}
	 * 
	 * @return
	 */
	Iterable<Class<?>> installableClosures();

	/**
	 * Mappings are a correspondence from a java class to a positive number. If any implementation
	 * of this provides a single mapping, the configuration shall be considered frozen, that is,
	 * runtime registration will not be available. These should be provided when one intends to use
	 * this serialization api for network serialization or persistent storage, since by using
	 * transient mappings one may end up getting distinct id lookups from one run to another.
	 * 
	 * @return
	 */
	Iterable<Map.Entry<Integer, Class<?>>> installableMappings();

	/**
	 * Replacements are APIs that should not be usually be present in user code, but are created by
	 * 3rd party software, such as Hibernate persistent collections. <br/>
	 * <br/>
	 * 
	 * @return
	 */
	Iterable<Map.Entry<Class<?>, Class<?>>> installableReplacements();

	/**
	 * Whenever serialization rules are too customized to be generated, one can supply a collection
	 * of pairs Class <=> Serializer to be installed, avoiding class generation for the given type.
	 * 
	 * @return
	 */
	Iterable<Map.Entry<Class<?>, Serializer>> installableSerializers();

	/**
	 * Hook up Registration Listeners to this module.
	 * 
	 * @return
	 */
	Iterable<RegistrationListener> listeners();
}
